<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<title>Introduction to Atom</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<style type="text/css" media="screen">
  @import "../css/common.css";
  @import "../css/documentation.css";
  #main h2 { font-size: 200%; }
  pre { padding-left: 3em; }
</style>
<script type="text/javascript"><!-- --></script>
</head>
<body>

<div id="logo">
<h1><a href="/"><span id="feed"><span id="f">F</span><span id="e1">E</span><span id="e2">E</span></span><span id="d">D</span> Validator</a></h1>
<p>Introduction to Atom</p>
<a class="skip" href="#startnavigation">Jump to navigation</a>
</div> <!--logo-->

<div id="main">

<h2>Contents</h2>
<ul>
<li><a href="#whatIsAtom">What is Atom?</a>
<ul>
<li><a href="#aboutThisDocument">About this document</a></li>
<li><a href="#sampleFeed">Sample feed</a></li>
</ul>
</li>
<li>Feed Elements
<ul>
<li><a href="#requiredFeedElements">Required</a></li>
<li><a href="#recommendedFeedElements">Recommended</a></li>
<li><a href="#optionalFeedElements">Optional</a></li>
</ul>
</li>
<li>Entry Elements
<ul>
<li><a href="#requiredEntryElements">Required</a></li>
<li><a href="#recommendedEntryElements">Recommended</a></li>
<li><a href="#optionalEntryElements">Optional</a></li>
</ul>
</li>
<li>Common Constructs
<ul>
<li><a href="#category">Category</a></li>
<li><a href="#contentElement">Content</a></li>
<li><a href="#link">Link</a></li>
<li><a href="#person">Person</a></li>
<li><a href="#text">Text</a></li>
</ul>
</li>
<li><a href="#extensibility">Extending Atom</a></li>
<li><a href="#seeAlso">See Also</a></li>
</ul>

<h2>What is Atom?<a id="whatIsAtom" name="whatIsAtom"></a></h2>
<p>Atom is the name of an XML-based Web content and metadata syndication format, and an application-level protocol for publishing and editing Web resources belonging to periodically updated websites.</p>
<p>All Atom feeds must be well-formed <a href="http://www.w3.org/TR/REC-xml">XML</a> documents, and are identified with the <code>application/atom+xml</code> media type.</p>
<h3>About this document<a id="aboutThisDocument" name="aboutThisDocument"> </a></h3>
<p>This document focuses on 
<a href="rfc4287.html">The Atom Syndication Format</a>
produced by the 
<a href="http://www.ietf.org/" title="Internet Engineering Task Force">IETF</a>
<a href="http://www.ietf.org/html.charters/atompub-charter.html">AtomPub Working Group</a>.  In the event that this document differs from the Internet Draft, the Internet Draft is to be considered authoritative.</p>
<p>General considerations:</p>
<ul>
<li>All elements described in this document must be in the <a href="http://www.w3.org/2005/Atom">http://www.w3.org/2005/Atom</a> namespace.</li>
<li>All timestamps in Atom must conform to <a href="http://www.faqs.org/rfcs/rfc3339.html">RFC 3339</a>.</li>
<li>Unless otherwise specified, all values must be plain text (i.e., no entity-encoded html).</li>
<li><a href="http://www.w3.org/TR/REC-xml/#sec-lang-tag"><code>xml:lang</code></a> may be used to identify the language of any human readable text.</li>
<li><a href="http://www.w3.org/TR/xmlbase/"><code>xml:base</code></a> may be used to control how relative <abbr title="Universal Resource Identifier">URI</abbr>s are resolved.</li>
</ul>

<h3>Sample feed<a id="sampleFeed" name="sampleFeed"> </a></h3>
<pre>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;feed xmlns="http://www.w3.org/2005/Atom"&gt;

  &lt;title&gt;Example Feed&lt;/title&gt;
  &lt;link href="http://example.org/"/&gt;
  &lt;updated&gt;2003-12-13T18:30:02Z&lt;/updated&gt;
  &lt;author&gt;
    &lt;name&gt;John Doe&lt;/name&gt;
  &lt;/author&gt;
  &lt;id&gt;urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6&lt;/id&gt;

  &lt;entry&gt;
    &lt;title&gt;Atom-Powered Robots Run Amok&lt;/title&gt;
    &lt;link href="http://example.org/2003/12/13/atom03"/&gt;
    &lt;id&gt;urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a&lt;/id&gt;
    &lt;updated&gt;2003-12-13T18:30:02Z&lt;/updated&gt;
    &lt;summary&gt;Some text.&lt;/summary&gt;
  &lt;/entry&gt;

&lt;/feed&gt;
</pre>

<h2>Elements of &lt;feed&gt;</h2>

A Feed consists of some metadata, followed by any number of entries.

<h3>Required feed elements<a id="requiredFeedElements" name="requiredFeedElements"> </a></h3>
<p>Here's a list of the required feed elements, each with a brief description, and an example.</p>

<table cellspacing="10">
<tr>
<th>Element</th>
<th>Description</th>
</tr>

<tr>
<td valign="top">id</td>
<td valign="top">Identifies the feed using a universally unique and permanent
<abbr title="Universal Resource Identifier">URI</abbr>.
If you have a long-term, renewable lease on your Internet domain name,
then you can feel free to use your website's address.
<pre>&lt;id&gt;http://example.com/&lt;/id&gt;</pre></td>
</tr>

<tr>
<td valign="top">title</td>
<td valign="top">Contains a human readable title for the feed.  Often the same
as the title of the associated website.  This value should not be blank.
<pre>&lt;title&gt;Example, Inc.&lt;/title&gt;</pre></td>
</tr>

<tr>
<td valign="top">updated</td>
<td valign="top">Indicates the last time the feed was modified in a
significant way.
<pre>&lt;updated&gt;2003-12-13T18:30:02Z&lt;/updated&gt;</pre></td>
</tr>
</table>

<h3>Recommended feed elements<a id="recommendedFeedElements" name="recommendedFeedElements"> </a></h3>
Atom makes a number of additional requirements and recommendations for feed elements that you should to be aware of.  They are as follows:

<table cellspacing="10">
<tr>
<th>Element</th>
<th>Description</th>
</tr>

<tr>
<td valign="top">author</td>
<td valign="top">Names one author of the feed.  A feed may have multiple
<code>author</code> elements.  A feed must contain at least one 
<code>author</code> element unless <b>all</b> of the <code>entry</code>
elements contain at least one <code>author</code> element.  More
info <a href="#person">here</a>.
<pre>&lt;author&gt;
&nbsp;&nbsp;&lt;name&gt;John&nbsp;Doe&lt;/name&gt;
&nbsp;&nbsp;&lt;email&gt;JohnDoe@example.com&lt;/email&gt;
&nbsp;&nbsp;&lt;uri&gt;http://example.com/~johndoe&lt;/uri&gt;
&lt;/author&gt;</pre></td>
</tr>

<tr>
<td valign="top">link</td>
<td valign="top">Identifies a related Web page.  The type of relation is defined by the <code>rel</code> attribute.  A feed is limited to one <code>alternate</code> per <code>type</code> and <code>hreflang</code>.  A feed should contain a link back to the feed itself.  More info <a href="#link">here</a>.
<pre>&lt;link&nbsp;rel="self" href="/feed"&nbsp;/&gt;</pre></td>
</tr>

</table>

<h3>Optional feed elements<a id="optionalFeedElements" name="optionalFeedElements"> </a></h3>
<p>Here's a list of optional feed elements.</p>
<table cellspacing="10">
<tr>
<th>Element</th>
<th>Description</th>
</tr>

<tr>
<td valign="top">category</td>
<td valign="top">Specifies a category that the feed belongs to.  A <code>feed</code> may have multiple <code>category</code> elements.  More info <a href="#category">here</a>.
<pre>&lt;category term="sports"/&gt;</pre></td>
</tr>

<tr>
<td valign="top">contributor</td>
<td valign="top">Names one contributor to the feed. An feed may have multiple contributor elements.  More info <a href="#person">here</a>.
<pre>&lt;contributor&gt;
&nbsp;&nbsp;&lt;name&gt;Jane&nbsp;Doe&lt;/name&gt;
&lt;/contributor&gt;</pre></td>
</tr>

<tr>
<td valign="top">generator</td>
<td valign="top">Identifies the software used to generate the feed, for debugging and other purposes.  Both the <abbr title="Uniform Resource Identifier">uri</abbr> and <code>version</code> attributes are optional.
<pre>&lt;generator uri="/myblog.php" version="1.0"&gt;
&nbsp;&nbsp;Example Toolkit
&lt;/generator&gt;</pre></td>
</tr>

<tr>
<td valign="top">icon</td>
<td valign="top">Identifies a small image which provides iconic visual identification for the feed.  Icons should be square.
<pre>&lt;icon&gt;/icon.jpg&lt;/icon&gt;</pre></td>
</tr>

<tr>
<td valign="top">logo</td>
<td valign="top">Identifies a larger image which provides visual identification for the feed.  Images should be twice as wide as they are tall.
<pre>&lt;logo&gt;/logo.jpg&lt;/logo&gt;</pre></td>
</tr>

<tr>
<td valign="top">rights</td>
<td valign="top">Conveys information about rights, e.g. copyrights, held in and over the feed.  More info <a href="#text">here</a>.
<pre>&lt;rights&gt; &copy; 2005 John Doe &lt;/rights&gt;</pre></td>
</tr>

<tr>
<td valign="top">subtitle</td>
<td valign="top">Contains a human-readable description or subtitle for the feed.  More info <a href="#text">here</a>.
<pre>&lt;subtitle&gt;all your examples are belong to us&lt;/subtitle&gt;</pre></td>
</tr>
</table>

<h2>Elements of &lt;entry&gt;</h2>

An example of an entry would be a single post on a weblog.

<h3>Required Elements of &lt;entry&gt;<a id="requiredEntryElements" name="requiredEntryElements"> </a></h3>

<p>Here's a list of the required feed elements, each with a brief description, and an example.</p>

<table cellspacing="10">
<tr>
<th>Element</th>
<th>Description</th>
</tr>

<tr>
<td valign="top">id</td>
<td valign="top">Identifies the entry using a universally unique and permanent
<abbr title="Universal Resource Identifier">URI</abbr>.
Suggestions on how to make a good id can be found
<a href="http://diveintomark.org/archives/2004/05/28/howto-atom-id">here</a>.
Two entries in a feed can have the same value for id if they represent the
same entry at different points in time.
<pre>&lt;id&gt;http://example.com/blog/1234&lt;/id&gt;</pre></td>
</tr>

<tr>
<td valign="top">title</td>
<td valign="top">Contains a human readable title for the entry.
This value should not be blank.
<pre>&lt;title&gt;Atom-Powered Robots Run Amok&lt;/title&gt;</pre></td>
</tr>

<tr>
<td valign="top">updated</td>
<td valign="top">Indicates the last time the entry was modified in a
significant way.  This value need not change after a typo is fixed, only
after a substantial modification.  Generally, different entries in a feed
will have different updated timestamps.
<pre>&lt;updated&gt;2003-12-13T18:30:02-05:00&lt;/updated&gt;</pre></td>
</tr>

</table>

<h3>Recommended elements of &lt;entry&gt;<a id="recommendedEntryElements" name="recommendedEntryElements"> </a></h3>
Atom makes a number of additional requirements and recommendations for entry elements that you should to be aware of.  They are as follows:

<table cellspacing="10">
<tr>
<th>Element</th>
<th>Description</th>
</tr>

<tr>
<td valign="top">author</td>
<td valign="top">Names one author of the entry.  An entry
may have multiple authors.  An entry must contain at least one 
<code>author</code> element unless there is an <code>author</code> element
in the enclosing <code>feed</code>, or there is an <code>author</code> element
in the enclosed <code>source</code> element.
More info <a href="#person">here</a>.
<pre>&lt;author&gt;
&nbsp;&nbsp;&lt;name&gt;John&nbsp;Doe&lt;/name&gt;
&lt;/author&gt;</pre></td>
</tr>

<tr>
<td valign="top">content</td>
<td valign="top">Contains or links to the complete content of the entry.  Content must be provided if there is no <code>alternate</code> link, and should be provided if there is no <code>summary</code>.  More info <a href="#content">here</a>.
<pre>&lt;content&gt;complete story here&lt;/content&gt;</pre></td>
</tr>

<tr>
<td valign="top">link</td>
<td valign="top">Identifies a related Web page.  The type of relation is defined by the <code>rel</code> attribute.  An entry is limited to one <code>alternate</code> per <code>type</code> and <code>hreflang</code>.  An entry must contain an <code>alternate</code> link if there is no <code>content</code> element.  More info <a href="#link">here</a>.
<pre>&lt;link rel="alternate" href="/blog/1234"/&gt;</pre></td>
</tr>

<tr>
<td valign="top">summary</td>
<td valign="top">Conveys a short summary, abstract, or excerpt of the entry.  Summary should be provided if there either is no content provided for the entry, or that content is not inline (i.e., contains a src attribute), or if the content is encoded in base64.  More info <a href="#text">here</a>.
<pre>&lt;summary&gt;Some text.&lt;/summary&gt;</pre></td>
</tr>

</table>

<h3>Optional elements of &lt;entry&gt;<a id="optionalEntryElements" name="optionalEntryElements"> </a></h3>
<p>Here's a list of optional feed elements.</p>

<table cellspacing="10">
<tr>
<th>Element</th>
<th>Description</th>
</tr>

<tr>
<td valign="top">category</td>
<td valign="top">Specifies a category that the entry belongs to.  A <code>entry</code> may have multiple <code>category</code> elements.  More info <a href="#category">here</a>.
<pre>&lt;category term="technology"/&gt;</pre></td>
</tr>

<tr>
<td valign="top">contributor</td>
<td valign="top">Names one contributor to the entry. An entry may have multiple <code>contributor</code> elements.  More info <a href="#person">here</a>.
<pre>&lt;contributor&gt;
&nbsp;&nbsp;&lt;name&gt;Jane&nbsp;Doe&lt;/name&gt;
&lt;/contributor&gt;</pre></td>
</tr>

<tr>
<td valign="top">published</td>
<td valign="top">Contains the time of the initial creation or first availability of the entry.
<pre>&lt;published&gt;2003-12-13T09:17:51-08:00&lt;/published&gt;</pre></td>
</tr>

<tr>
<td valign="top">rights</td>
<td valign="top">Conveys information about rights, e.g. copyrights, held in and over the entry.  More info <a href="#text">here</a>.
<pre>&lt;rights type="html"&gt;
&nbsp;&nbsp;&amp;amp;copy; 2005 John Doe
&lt;/rights&gt;</pre></td>
</tr>

<tr>
<td valign="top">source</td>
<td valign="top">Contains metadata from the source feed if this
entry is a copy.
<pre>&lt;source&gt;
&nbsp;&nbsp;&lt;id&gt;http://example.org/&lt;/id&gt;
&nbsp;&nbsp;&lt;title&gt;Example, Inc.&lt;/title&gt;
&nbsp;&nbsp;&lt;updated&gt;2003-12-13T18:30:02Z&lt;/updated&gt;
&lt;/source&gt;</pre></td>
</tr>

</table>

<h2>Common Constructs</h2>

<h3 id="category">Category<a name="category"> </a></h3>
<p><code>&lt;category&gt;</code> has one required attribute, <code>term</code>, and two optional attributes, <code>scheme</code> and <code>label</code>.</p>
<p><code>term</code> identifies the category</p>
<p><code>scheme</code> identifies the categorization scheme via a 
<abbr title="Universal Resource Identifier">URI</abbr>.
</p>
<p><code>label</code> provides a human-readable label for display</p>

<h3>Content<a id="contentElement" name="contentElement"> </a></h3>
<p><code>&lt;content&gt;</code> either contains, or links to, the complete content of the entry.</p>
<p>In the most common case, the <code>type</code> attribute is either <code>text</code>, <code>html</code>, <code>xhtml</code>, in which case the content element is defined identically to other text constructs, which are described <a href="#text">here</a>.</p>
<p>Otherwise, if the <code>src</code> attribute is present, it represents the <abbr title="Universal Resource Identifier">URI</abbr> of where the content can be found.  The <code>type</code> attribute, if present, is the media type of the content.</p>
<p>Otherwise, if the <code>type</code> attribute ends in <code>+xml</code> or <code>/xml</code>, then an xml document of this type is contained inline.</p>
<p>Otherwise, if the <code>type</code> attribute starts with <code>text</code>, then an escaped document of this type is contained inline.</p>
<p>Otherwise, a <a href="http://www.faqs.org/rfcs/rfc3548.html">base64</a> encoded document of the indicated media type is contained inline.</p>

<h3 id="link">Link<a name="link"> </a></h3>
<p><code>&lt;link&gt;</code> is patterned after html's <a href="http://www.w3.org/TR/1999/REC-html401-19991224/struct/links.html#h-12.3">link</a> element.  It has one required attribute, <code>href</code>, and five optional attributes: <code>rel</code>, <code>type</code>, <code>hreflang</code>, <code>title</code>, and <code>length</code>.</p>
<p><code>href</code> is the <abbr title="Universal Resource Identifier">URI</abbr> of the referenced resource (typically a Web page)</p>
<p><code>rel</code> contains a single link relationship type.  It can be a full <abbr title="Universal Resource Identifier">URI</abbr> (see <a href="#extensibility">extensibility</a>), or one of the following predefined values (default=<code>alternate)</code>:</p>
<ul>
<li><code>alternate</code>: an alternate representation of the entry or feed, for example a permalink to the html version of the entry, or the front page of the weblog.</li>
<li><code>enclosure</code>: a related resource which is potentially large in size and might require special handling, for example an audio or video recording.</li>
<li><code>related</code>: an document related to the entry or feed.</li>
<li><code>self</code>: the feed itself.</li>
<li><code>via</code>: the source of the information provided in the entry.</li>
</ul>
<p><code>type</code> indicates the media type of the resource.</p>
<p><code>hreflang</code> indicates the language of the referenced resource.</p>
<p><code>title</code> human readable information about the link, typically for display purposes.</p>
<p><code>length</code> the length of the resource, in bytes.</p>

<h3 id="person">Person<a name="person"> </a></h3>
<p><code>&lt;author&gt;</code> and <code>&lt;contributor&gt;</code> describe a person, corporation, or similar entity.  It has one required element, <code>name</code>, and two optional elements: <code>uri</code>, <code>email</code>.</p>
<p><code>&lt;name&gt;</code> conveys a human-readable name for the person.</p>
<p><code>&lt;uri&gt;</code> contains a home page for the person.</p>
<p><code>&lt;email&gt;</code> contains an email address for the person.</p>

<h3 id="text">Text<a name="text"> </a></h3>
<p><code>&lt;title&gt;</code>, <code>&lt;summary&gt;</code>, <code>&lt;content&gt;</code>, and <code>&lt;rights&gt;</code> contain human-readable text, usually in small quantities.  The <code>type</code> attribute determines how this information is encoded (default="text")</p>
<p>If <code>type="text"</code>, then this element contains plain text with no entity escaped html.</p>
<pre>&lt;title type="text"&gt;AT&amp;amp;T bought by SBC!&lt;/title&gt;</pre>
<p>If <code>type="html"</code>, then this element contains entity escaped html.</p>
<pre>&lt;title type="html"&gt;
&nbsp;&nbsp;AT&amp;amp;amp;T bought &amp;amp;lt;b&amp;amp;gt;by SBC&amp;amp;lt;/b&amp;amp;gt;!
&lt;/title&gt;</pre>
<p>If <code>type="xhtml"</code>, then this element contains inline xhtml, wrapped in a div element.</p>
<pre>&lt;title type="xhtml"&gt;
&nbsp;&nbsp;&lt;div xmlns="http://www.w3.org/1999/xhtml"&gt;
&nbsp;&nbsp;&nbsp;&nbsp;AT&amp;amp;T bought &lt;b&gt;by SBC&lt;/b&gt;!
&nbsp;&nbsp;&lt;/div&gt;
&lt;/title&gt;</pre>

<h2 id="extensibility">Extending Atom<a name="extensibility"> </a></h2>
<p>The atom content element is designed to support the direct inclusion of other XML vocabularies.</p>
<p>Any fully qualified <abbr title="Universal Resource Identifier">URI</abbr> may be used a value for the rel attribute of <code>link</code> elements.</p>
<p>Elements from other namespaces may be included pretty much anywhere.  This means that most <a href="http://directory.google.com/Top/Reference/Libraries/Library_and_Information_Science/Technical_Services/Cataloguing/Metadata/RDF/Applications/RSS/Specifications/RSS_1.0_Modules/">RSS 1.0</a> and <a href="http://blogs.law.harvard.edu/tech/directory/5/specifications/rss20ModulesNamespaces">RSS 2.0</a> modules may be used in Atom.</p>

<h2 id="seeAlso">See Also<a name="seeAlso"> </a></h2>
<ul>
<li><a href="http://www.atomenabled.org/developers/syndication/atom-format-spec.php">The Atom Syndication Format</a></li>
<li><a href="http://www.intertwingly.net/wiki/pie/KnownAtomFeeds">Examples of Atom 1.0 Feeds</a></li>
<li><a href="http://feedvalidator.org/">Feed Validator</a></li>
<li><a href="http://www-128.ibm.com/developerworks/xml/library/x-atom10.html">DeveloperWorks Overview</a></li>
<li><a href="http://www.intertwingly.net/wiki/pie/Rss20AndAtom10Compared">RSS 2.0 and Atom 1.0 Compared</a></li>
<li><a href="http://www.ietf.org/html.charters/atompub-charter.html">IETF Charter</a></li>
<li><a href="http://www.intertwingly.net/wiki/pie/FrontPage">Atom Wiki</a></li>
</ul>

<div class="centered">
<a name="startnavigation" id="startnavigation"></a>
<div class="navbarWrapper">
    <div class="navbarContent">
        <img class="borderTL" src="../images/borderTL.gif" alt="" width="14" height="14" />
        <img class="borderTR" src="../images/borderTR.gif" alt="" width="14" height="14" />
<p>
<a href="/">Home</a> &middot;
<a href="/about.html">About</a> &middot;
<a href="/news/">News</a> &middot;
<a href="/docs/">Docs</a> &middot;
<a href="/terms.html">Terms</a>
</p>

        <div class="roundedCornerSpacer">&nbsp;</div>
    </div><!-- .content -->
    <div class="bottomCorners">
        <img class="borderBL" src="../images/borderBL.gif" alt="" width="14" height="14" />
        <img class="borderBR" src="../images/borderBR.gif" alt="" width="14" height="14" />
    </div><!-- .bottomCorners -->
</div><!-- .contentWrapper --> 
</div><!-- .centered -->
</div><!-- .main -->

</body>
</html>
